Java 3D API Specification

A P P E N D I X D

THE Java 3D API uses the standard Java exception model for handling errors or exceptional conditions. In addition to using existing exception classes, such as ArrayIndexOutOfBoundsException and IllegalArgumentException, Java 3D defines several new runtime exceptions. These exceptions are thrown by various Java 3D methods or by the Java 3D renderer to indicate an error condition of some kind.

The exceptions defined by Java 3D, as part of the javax.media.j3d package, are described in the following sections. They all extend RuntimeException and, as such, need not be declared in the throws clause of methods that might cause the exception to be thrown. This appendix is not an exhaustive list of all exceptions expected for Java 3D. Additional exceptions will be added as the need arises.

D.1 BadTransformException

Indicates an attempt to use a Tranform3D object that is inappropriate for the object in which it is being used. For example:

• Transforms that are used in the scene graph, within a TransformGroup node, must be affine. They may optionally contain a non-uniform scale and/or a shear, subject to other listed restrictions.

• All transforms in the TransformGroup nodes above a ViewPlatform object must be congruent. This ensures that the Vworld coordinates to ViewPlatform coordinates transform is angle and length-preserving with no shear and only uniform scale.

• Most viewing transforms other than those in the scene graph can only contain translation and rotation.

• The projection transform is allowed to be non-affine, but it must either be a single point perspective projection or a parallel projection.

Constructors

public BadTransformException()
public BadTransformException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.2 CapabilityNotSetException

This exception indicates an access to a live or compiled Scene Graph object without the required capability set.

Constructors

public CapabilityNotSetException()
public CapabilityNotSetException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.3 DanglingReferenceException

This exception indicates that during a cloneTree call, an updated reference was requested for a node that did not get cloned. This occurs when a sub-graph is duplicated via cloneTree and has at least one Leaf node that contains a reference to a Node with no corresponding node in the cloned sub-graph. This results in two Leaf nodes wanting to share access to the same Node.

If dangling references are to be allowed during the cloneTree call, cloneTree should be called with the allowDanglingReferences parameter set to true.

Constructors

public DanglingReferenceException()
public DanglingReferenceException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.4 IllegalSharingException

This exception indicates an illegal attempt to share a scene graph object. For example, the following are illegal:

• referencing a shared subgraph in more than one virtual universe

• using the same component object both in the scene graph and in an immediate mode graphics context

• including an unsupported type of leaf node within a shared subgraph

• referencing a BranchGroup node in more than one of the following ways:

• attaching it to a (single) Locale
• adding it as a child of a Group node within the scene graph
• referencing it from a (single) Background leaf node as background geometry

Constructors

public IllegalSharingException()
public IllegalSharingException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.5 MultipleParentException

This exception extends IllegalSharingException and indicates an attempt to add a node that is already a child of one group node into another group node.

Constructors

public MultipleParentException()
public MultipleParentException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.6 RestrictedAccessException

This exception indicates an attempt to access or modify a state variable without permission to do so. For example, invoking a set method for a state variable that is currently read-only.

Constructors

public RestrictedAccessException()
public RestrictedAccessException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.7 SceneGraphCycleException

This exception indicates that one of the live scene graphs attached to a viewable Locale has a cycle in it. Java 3D scene graphs are directed acyclic graphs and, as such, do not permit cycles. This exception is either thrown by the Java 3D renderer at scene graph traversal time or when a scene graph containing a cycle is made live (added as a descendant of a Locale object).

Constructors

public SceneGraphCycleException()
public SceneGraphCycleException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.8 SingularMatrixException

This exception, in the java.vecmath package, indicates that the inverse of a matrix cannot be computed.

Constructors

public SingularMatrixException()
public SingularMatrixException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.9 SoundException

This exception indicates a problem in loading or playing a sound sample.

Constructors

public SoundException()
public SoundException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

---

Java 3D API Specification

Copyright © 1997, Sun Microsystems, Inc. All rights reserved.